📩 Envío de mensajes con WhatsApp API

WhatsApp API permite a las compañías automatizar y personalizar la comunicación con sus clientes, facilitando interacciones eficientes, escalables y enriquecidas con contenido multimedia. Es ideal para gestionar consultas, enviar notificaciones y ofrecer respuestas inmediatas a través de IA Agents.

🚀 Tipo de datos de Envío de Mensajes

WhatsApp API facilita la gestión eficiente de interacciones en WhatsApp. Permite enviar mensajes masivos, ofrecer respuestas personalizadas en tiempo real y adaptarse a las necesidades de cada cliente. Además, ayuda a crear procesos optimizados que mejoran la experiencia del usuario y cumplen con los objetivos comerciales.

⚙️ Configuración del Envío de Mensajes

🔹 Paso 1: Definir el Endpoint

Para enviar mensajes, debes utilizar el siguiente endpoint de la API: https://api.jelou.ai/v2/whatsapp/:botId/hsm

🔹 Paso 2: Parámetros de la Solicitud

Los parámetros clave para la solicitud incluyen:

Texto: El contenido del mensaje.
Tipo de dato de mensaje (type): Define el Tipo de dato de plantilla que se va a enviar.
Propiedad de plantilla: Plantilla previamente creada y aprobada por META.
Archivo multimedia: Si la plantilla requiere alguna URL (imagen, documento, etc.).
Bot ID: Identificador único del bot.
Parámetros: Datos específicos para cada envío (Propiedad, número de pedido, etc.).
Archivo Multimedia: URL pública del archivo (imagen, vídeo, documento).

🔹 Paso 3: Enviar la Solicitud

Envía el mensaje usando el método POST. Al completar el envío, recibirás una respuesta que te permitirá verificar el estado de la entrega.

💡 Asegúrate de cumplir con las políticas de WhatsApp para evitar restricciones.

Restricciones de Contenido

Recuerda que, para enviar mensajes a través de WhatsApp, debes usar plantillas previamente aprobadas por META.

Cada plantilla tiene limitaciones específicas según su formato y contenido, como la longitud del mensaje o el Tipo de dato de información permitida. Asegúrate de revisar estas restricciones antes de utilizarlas para garantizar su correcto envío.

Considera que:

No se permiten URLs, emojis ni archivos multimedia dentro de los mensajes de autenticación.
Los parámetros deben tener un máximo de 15 caracteres.

Para más información sobre lo que puedes y no puedes hacer con plantillas, [visita Tipo de datos de plantillas](https://www.notion.so/Tipo de datos-de-Plantillas-c3912b6345604d68b71f027ad1038e61?pvs=21).

Envío de mensajes

➡️ POST https://api.jelou.ai/v2/whatsapp/:botId/hsm

Envía una plantilla de mensaje a los usuarios de WhatsApp.

Request Body

Propiedad	Tipo de dato	Descripción	Obligatoriedad
mediaUrl	string	Especifica la URL del archivo multimedia; esta debe de ser pública para su uso. Obligatoria si tu plantilla es de Tipo de dato video, imagen o documento; opcional para otros Tipo de datos.	Obligatorio
filename	string	Propiedad del archivo que se recibe dentro de una plantilla de Tipo de dato documento.	Obligatorio
type	string	Define el Tipo de dato de mensaje de la plantilla: text, hsm, image, document, video, catalog, copy code (LTO), carousel, quick_reply, url. Obligatorio para imagen, video o documento.Por defecto es texto si no se especifica.	Obligatorio
language	string	Idioma en el que se encuentra la plantilla: en, spa, pt (inglés, español y portugués)	Obligatorio
elementName	string	El Propiedad de la plantilla. Puedes obtenerlo en la UI desde Campañas -> Plantillas, en el campo "Plantilla".	Obligatorio
parameters	array	Conjunto de cadenas que reemplazar valores en la plantilla del mensaje.	Obligatorio
destination	array	Lista de números de clientes para el envió de mensajes. El formato debe ser numérico, incluir el código de país y excluir el signo +, guiones o espacios (ejemplo: 593999xxxxxx).	Obligatorio
buttonPayloads	array	Información para los botones de respuesta rápida, requerido si la plantilla los incluye.	Opcional
actions	objeto	Configuración y acciones de la plantilla en formato payload.	Opcional
HeaderParameters	string	Encabezados personalizados que pueden ser necesarios según las especificaciones del cliente en las plantillas de [texto](https://www.notion.so/Tipo de datos-de-Plantillas-c3912b6345604d68b71f027ad1038e61?pvs=21) y [catálogo multiproducto](https://www.notion.so/Tipo de datos-de-Plantillas-c3912b6345604d68b71f027ad1038e61?pvs=21).	Opcional
Thumbnail Product	String	URL donde está alojada la imagen en miniatura. Obligatoria al usar la plantilla de catálogo.	Obligatorio
ExpirationTime	String	Especifica el tiempo de expiración de un recurso o contenido, en formato de fecha y hora.	Opcional
campaignId	String	Identificador único de la campaña asociada al contenido.	Opcional
origin	String	Fuente o lugar de origen del contenido.	Opcional
sub_type	String	SubTipo de dato del elemento, necesario si el Tipo de dato es de botón.	Obligatorio (si type es de Tipo de dato botón)
buttonOptions	Objeto	Opciones configurables para los botones que tienen configuración de un solo uso.	Opcional
ltoParams	Objeto	Parámetros de [tiempo limitado](https://www.notion.so/Tipo de datos-de-Plantillas-c3912b6345604d68b71f027ad1038e61?pvs=21) asociados con la acción o contenido. Se ingresa en milisegundos.	Opcional
buttonParameters	Objeto	Permite realizar la configuración de todos los Tipo de datos de [botones](https://www.notion.so/Tipo de datos-de-Plantillas-c3912b6345604d68b71f027ad1038e61?pvs=21).	Opcional
cards	Array of Object	Tarjetas de contenido que se mostrarán en la interfaz de usuario. Pueden verse en la [plantilla de carrusel.](https://www.notion.so/Tipo de datos-de-Plantillas-c3912b6345604d68b71f027ad1038e61?pvs=21)	Opcional

Solicitud de API de Ejemplo

Tipo de datos de Plantillas

En esta sección, ofrecemos ejemplos de los JSON necesarios para estructurar y definir plantillas de mensajes de forma estándar y eficiente. Estos ejemplos son esenciales, ya que proporcionan una guía clara para que los clientes puedan sustituir fácilmente los valores con sus propios datos, garantizando así un uso adecuado y consistente del API.

💡 Nota: Si el Propiedad de una plantilla o un botón dentro del texto JSON es distinto a la plantilla ya aprobada, ya sea incluso por una tilde, el envío fallará. La precisión es clave para garantizar la funcionalidad.

Para más información sobre este tema, visita [plantillas](https://www.notion.so/Tipo de datos-de-Plantillas-c3912b6345604d68b71f027ad1038e61?pvs=21).

Mensaje de texto

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1",
		"PARAMETER_2"
	],
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Mensaje con imagen

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1",
		"PARAMETER_2"
	],
	"mediaUrl": "https://amazon.com/cdn/sample.jpeg",
	"type": "image",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Mensaje con video

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1",
		"PARAMETER_2"
	],
	"mediaUrl":"https://amazon.com/cdn/test.mp4",
	"type": "video",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Mensaje con documento adjunto

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1"
	],
	"mediaUrl":"https://amazon.com/cdn/test.pdf",
	"type": "document",
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}'

Mensaje de texto con botones de acción de URL estática.

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"parameters": [
		"PARAMETER_1"
	],
	"destinations": [
		"593XXXXXXXX"
	],
	"elementName": "ELEMENT_NAME"
}

Mensaje de texto con botones de acción de URL dinámica

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Accept-Language: es' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"destinations": [
		"593XXXXXXXX"
	],
	"parameters": [
		"PARAMETER_1"
	],
	"elementName": "ELEMENT_NAME",
  "buttonParameters": [
    {
      "type": "URL",
      "payload": {
        "param": "PARAM_URL"
      }
    }
  ]
}

Mensaje de texto con botones de Quick Reply

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "elementName": "ELEMENT_NAME",
    "language": "es",
    "type": "text",
    "parameters": [
      "param1",
      "param2"
    ],
    "destinations": [
      "593XXXXXXXX"
    ],
    "buttonParameters": [
      {
        "type": "QUICK_REPLY",
        "payload": {
          "type": "edge",
          "action": "BTN1",
          "skillId": "1"
        }
      },
      {
        "type": "QUICK_REPLY",
        "payload": {
          "type": "edge",
          "action": "BTN2",
          "skillId": "2"
        }
      },
      {
        "type": "QUICK_REPLY",
        "payload": {
          "type": "edge",
          "action": "BTN3",
          "skillId": "3"
        }
      }
    ]
  }'

Mensaje de texto personalizado con parámetros en el encabezado

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "elementName": "test_template",
    "destinations": ["593XXXXXXXXX"],
    "parameters": [
		"PARAMETER_1",
		"PARAMETER_2"
	  ],
    "headerParameters": [
        "PARAMETER_VALUE"
    ]
}'

Catálogo Completo

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"elementName": "test_template",
	"destinations": [
		"593XXXXXXXX"
	],
	"parameters": [
		"PARAMETER_1"
	],
	"type": "catalog",
	"buttonParameters": [
		{
			"type": "CATALOG",
			"payload": {
				"thumbnailProduct": "productId"
			}
		}
	]
}'

LTO con botón de copiar código

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"buttonOptions": {},
	"elementName": "test_template",
	"destinations": [
		"593XXXXXXXX"
	],
	"parameters": [
		"PARAMETER_1",
		"PARAMETER_2"
	],
	"type": "image",
	"mediaUrl": "https://amazon.com/cdn/sample.jpeg",
	"ltoParams": {
		"expirationTime": 1733260800000
	},
	"buttonParameters": [
		{
			"type": "COPY_CODE",
			"param": 1,
			"payload": {
				"param": "20OFF"
			}
		}
	]
}'

Autenticación

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
	"buttonOptions": {},
	"elementName": "test_test_test",
	"destinations": [
		"593XXXXXXXX"
	],
	"parameters": [
		"PARAMETER_1"
	],
	"type": "hsm"
}'

Carrusel con 2 tarjetas

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/:botId/hsm/' \
  --header 'Authorization: Basic {{Base64EncodedUsername:Password}}' \
  --header 'Content-Type: application/json' \
  --data '{
    "elementName": "test_template",
    "destinations": ["593XXXXXXXXX"],
    "parameters": [],
    "type": "carousel",
    "cards": [
        {
            "mediaUrl": "mediaUrl",
            "params": [
                "VALOR_PARAMETRO"
            ],
            "buttonParameters": [
                {
                    "type": "QUICK_REPLY",
                    "payload": {
                        "action": "Boton 1",
                        "type": "edge",
                        "skillId": "45515",
                        "cardIndex": 0
                    }
                }
            ]
        },
        {
            "mediaUrl": "mediaUrl",
            "params": [
                "VALOR_PARAMETRO_1",
                "VALOR_PARAMETRO_2"
            ],
            "buttonParameters": [
                {
                    "type": "QUICK_REPLY",
                    "payload": {
                        "action": "Boton 2",
                        "type": "edge",
                        "skillId": "10192",
                        "cardIndex": 1
                    }
                }
            ]
        }
    ]
}'

Casos de uso comunes

1. Mensajes Personalizados

✨ Usa plantillas con variables para enviar mensajes adaptados a las necesidades de cada usuario (por ejemplo, recordatorios de pagos o actualizaciones de pedidos).

2. Automatización con Webhooks

🔄 Interacciones personalizadas según las respuestas de los usuarios, permitiendo una conversación más dinámico y eficiente.

Ejemplos de campañas:

Promociones Personalizadas: Ofertas exclusivas según preferencias del cliente.
Recordatorios de Pagos: Notificaciones automáticas para vencimientos de facturas.
Cotizaciones de Servicios: Consultas rápidas sobre seguros, préstamos, etc.

Datos para configuración avanzada de campañas

Número Telefónico: Al ser un envío individual, el número de teléfono a quien le llegará la campaña deberá de estar en el formato correcto para que el envío sea exitoso.

Se debe omitir el signo +, incluir el código de país, solo pueden ingresar caracteres numéricos. Los guiones o espacios no son aceptados.

Para usuarios de Ecuador: Se debe omitir el signo “+” y el primer 0 del número telefónico para poder ser ingresado de manera correcta.

✅ Forma correcta	❌ Forma incorrecta	❌ Forma incorrecta
593xx9088x05	+593xx90x05	09xx90x05

Parámetros Específicos: Dependiendo de la campaña, puedes usar datos personalizados como el Tipo de dato de mensaje o información adicional de los clientes.

Personalización de Mensajes

Vinculación con Skills

Cada mensaje puede estar asociado a una skill específica que define cómo se debe manejar la respuesta del usuario. Esto es útil para crear interacciones más complejas y dirigidas, como menús interactivos o encuestas.

Configuración de Botones

Button Payload

Puedes usar la siguiente estructura en el campo *buttonPayloads* cuando tu plantilla incluya [botones de respuesta rápida](https://www.notion.so/Tipo de datos-de-Plantillas-c3912b6345604d68b71f027ad1038e61?pvs=21) usando skills; esto te permitirá activar flujos adicionales dentro de la conversación según la acción seleccionada por el usuario.

[
  {
    type: "edge",
    action: "Yes",
    skillId: "1",
  },
  {
    type: "edge",
    action: "Reschedule",
    skillId: "2",
  },
  {
    type: "edge",
    action: "Cancel",
    skillId: "3",
  },
];

En este caso, cada botón debe tener las claves *type*, *action* y *skillId*. La clave *action* define el texto que aparecerá en el botón, mientras que *skillId* indica el ID la skill que el botón activará. (Si no tienes claro el *skillId*, te recomendamos contactar al equipo de Jelou para obtener más información.)

Actions Payload

Redirigen a los usuarios a skills específicos según su elección o interacción.

Las plantillas permiten las siguientes configuraciones:

{
  "actions": {
    "setSkill": {
      "id": 2222
    }
  }
}

{
  "actions": {
    "setMemoryParams": {
      "url": "https://apps.jelou.ai"
    }
  }
}

Parámetros Cache

Esta función se utiliza para guardar información adicional en la caché para utilizarla posteriormente. Dependerá de la configuración deseada para la plantilla. Si se envía una URL, puede ser utilizada por un skill para redirigir esa URL con fines de marketing.

Todos los parámetros a almacenar en caché deben ir en setMemoryParams con sus respectivos campos clave-valor.

💡 Esta configuración será válida durante 3 meses.

{
  "actions": {
    "setMemoryParams": {
      "url": "https://apps.jelou.ai"
    }
  }
}

Herramientas Recomendadas para Pruebas y Ejecución

Para facilitar las pruebas y envío de solicitudes, te recomendamos usar herramientas como:

Postman
Insomnia

Estas herramientas permiten realizar solicitudes HTTP de manera sencilla, probar diferentes configuraciones y revisar las respuestas de la API.

Preguntas Frecuentes

¿Cuántos caracteres están permitidos?

No existe un límite actual definido para el numero de caracteres por mensaje; sin embargo hay que estar pendientes sobre el tamaño de los archivos que forman parte del mensaje; tales como: imagen, video o documento. Estos se comparten en mediaUrl.

En Jelou, tenemos las siguientes limitaciones de tamaño y formato a seguir:

DOCUMENTO: HASTA 15MB - FORMATO: .pdf
VIDEO: HASTA 15MB - FORMATO: .mp4
IMAGEN: HASTA 5MB - FORMATOS: .jpg, .jpeg, .png

¿Cómo se consume la API?

Los cURLS tanto de envío masivo como de envío 1-1 pueden ser consumidos en cualquier cliente HTTP como INSOMNIA O POSTMAN. Basta con crear una petición HTPP a través del cURL (simplemente pegándolo), luego cambiamos los datos y ejecutamos.

Este es un ejemplo con basic-auth

curl --request POST \
  --url 'https://api.jelou.ai/v2/whatsapp/+123456789000/hsm' \
  --header 'Accept-Language: es' \
  --header 'Authorization: Basic ==' \
  --header 'Content-Type: application/json' \
  --data '{
	"destinations": [
		"5939x9xx1xxx"
	],
	"parameters": [],
	"elementName": "test_template"
}'

🚀 Tipo de datos de Envío de Mensajes​

⚙️ Configuración del Envío de Mensajes​

🔹 Paso 1: Definir el Endpoint​

🔹 Paso 2: Parámetros de la Solicitud​

🔹 Paso 3: Enviar la Solicitud​

Restricciones de Contenido​

Envío de mensajes​